Repository navigation
test relative links in example documentation - #1811
KristofersJurevics wants to merge 1 commit into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ajbozarth
left a comment
ajbozarth
left a comment
There was a problem hiding this comment.
Some feedback from Claude: thanks for picking this up. The main issue is that the test doesn't run in CI yet; details inline. A few process items also need fixing before this can merge:
- DCO is failing: please amend with
git commit -s --amend(and, per AGENTS.md §7, swap theCo-authored-by: Copilottrailer forAssisted-by: GitHub Copilot). - The
labelcheck needs a conventional-commit PR title, e.g.test: check relative links in example docs. - Please fill in the body from
.github/pull_request_template.md, and link it withFixes #1810. - Please run
pre-commit installand then rerun the hooks;ruff formatcurrently fails on this file.
| @@ -0,0 +1,45 @@ | |||
| """Check that links in the example documentation point at real files.""" | |||
There was a problem hiding this comment.
CI won't collect this file. The pytest step in .github/workflows/quality.yml runs only test and tooling/docs-autogen/test_validate.py, so a test in docs/ only ever runs locally. Could you move it to test/test_example_links.py, next to test/test_example_collection.py? It will then run in CI and pick up the auto-applied unit marker. test/ files also need the SPDX license header; the hook excludes docs/, which is why it passes now. Update EXAMPLES_ROOT / REPOSITORY_ROOT for the new location.
| if line.strip().startswith("```"): | ||
| in_code_block = not in_code_block | ||
| continue | ||
| if in_code_block: | ||
| continue | ||
| yield from (first or second for first, second in LINK_RE.findall(line)) |
There was a problem hiding this comment.
Two parsing cases cause false positives: links inside inline code (`[x](missing.md)` gets flagged) and ~~~ fences (not treated as code blocks).
| if line.strip().startswith("```"): | |
| in_code_block = not in_code_block | |
| continue | |
| if in_code_block: | |
| continue | |
| yield from (first or second for first, second in LINK_RE.findall(line)) | |
| if line.strip().startswith(("```", "~~~")): | |
| in_code_block = not in_code_block | |
| continue | |
| if in_code_block: | |
| continue | |
| line = re.sub(r"`[^`]*`", "", line) | |
| yield from (first or second for first, second in LINK_RE.findall(line)) |
| parsed = urlsplit(target) | ||
| if parsed.scheme or parsed.netloc: | ||
| continue | ||
| target_path = (markdown_file.parent / parsed.path).resolve() |
There was a problem hiding this comment.
URL-encoded links like [x](my%20file.md) are reported as missing even when the file exists, so the path should be unquoted first:
| target_path = (markdown_file.parent / parsed.path).resolve() | |
| target_path = (markdown_file.parent / unquote(parsed.path)).resolve() |
|
|
||
| import re | ||
| from pathlib import Path | ||
| from urllib.parse import urlsplit |
There was a problem hiding this comment.
Paired with the unquote suggestion below:
| from urllib.parse import urlsplit | |
| from urllib.parse import unquote, urlsplit |
| return missing | ||
|
|
||
|
|
||
| def test_example_markdown_links_resolve(): |
There was a problem hiding this comment.
This only checks the current tree, which has no broken links, so nothing shows the check can actually fail. Could you add a couple of tmp_path tests that point _missing_links at a fixture directory (one broken link, one valid link with an anchor, one in a code block)? tooling/docs-autogen/test_validate.py has examples of this pattern. Making _missing_links take the root as a parameter would make that easy.
fixes issue #1810 by adding a regression test for broken relative links in example documentation. focused validation: 1 test passed; broader documentation checks previously had 5 passed and 19 skipped. Optional project dependencies remain unavailable locally.